These routines were written for and used in our Shareware program called
Eye On The Clock. These routines will take two dates and times and create a
string, in MANY different formats, of how much time there is between the two
dates and times. Basically you need to load up the Count_Rec structure and call
Get_Rel_Time_Str and your done.
These routines reference 'STR#' resource 129 for all text used to build the string
There are many supporting routines for both time/date stuff as well as strings
which may be useful on their own.
Here is an example of loading up the Count_Rec:
Count_Rec time_rec;
Str255 the_str;
time_rec.Display.fractional = FALSE;
time_rec.Display.significant = FALSE;
time_rec.Display.count_days = FALSE;
time_rec.Display.hide_zeros = FALSE;
time_rec.Display.allow_clock_display = FALSE;
time_rec.Display.allow_day_rounding = FALSE;
time_rec.Display.abbreviated = FALSE;
time_rec.Target_In_Secs = 2840227200; // target time to display (in seconds) 1/1/90
time_rec.From_In_Secs = 3000000000; // from time to display (in seconds)
// you may add only the items which you want displayed:
time_rec.Display.display_items = year + month + week + day + hour + minute + second;
Get_Rel_Time_Str (&time_rec, the_str);
// then display or use the_str)
The following are excerpts from the Eye On The Clock about file which should further describe the many display options that these routines have:
Eye On The Clock will display continuously updating time counters for important times and dates you configure. It will show the length of time until or since each event in a variety of user selectable formats. There can be events which reoccur at selectable intervals. Events might include:
• Keeping track of exactly how many days until a project is due
• Number of weeks until special holidays or events like birthdays and anniversaries
• Number of seconds until the weekend
• How many months old your baby is
• Number of days until vacation
Display Options:
--------------
Below the date and time boxes are a series of checkbox display options. There you can select which divisions of time you would like to see for the selected event.
For example, if the event is many years away, you may only wish to see how many years and months until the event. So check "Years" and "Months" and un-check "Weeks", "Days", "Hours", "Minutes" and "Seconds". Below the checkboxes is an example of how the display will look. As you change checkbox options, the example will change to reflect your selections.
Months are a special display type because of their varying lengths.
For example- if the current date 1/31/94 and the event date is set to 3/2/94, a result of "1-month 2-days" will be displayed. The computer tries to move forward 1 month but realizes that no 2/31/94 exists so it counts 1 month from 1/31 to be the last day of February (2/28/94) and then counts the days from there to the event. Notice that this can create some interesting results. A current date of 1/28 through 1/31 and the same event date of 3/2 will all yield the same result of 1-month 2-days. When the current date changes to 2/1, the display will change to 1-month 1-day.
Fractional checkbox:
The fractional checkbox will display the smallest checked time unit as a decimal number. Rather than an event being 1 month away, it will be displayed as 1.432 months away.
Only Display Largest Time Unit:
This checkbox lets you select many divisions of time, but will only display the largest applicable division. For example, if an event is 1 month away, and you have selected only weeks, days and minutes, then Eye On The Clock will just display the number of weeks until the event is less than a week away. Then the display will change to the next selected display type, days, until the event is less than a day away. Then the display will countdown the minutes until the event.
This is useful if you don't need a precise display, until the event is imminent.
Count Days since event:
For events in the past, this option counts the days. The day of the event is considered "Day #1" rather than '0 days since'. This will supersede all of the other display options (no hours, minutes, seconds etc.).
This setting will have no effect on events that are still in the future.
Hide Zeros:
This option controls whether or not Eye On The Clock will display time divisions which are zero. When Hide Zeros in on, even if you have years selected as a display option, you will not see any year value if the event is less than a year away.
Allow Clock display:
Selecting this option allows Eye On The Clock to display hours, minutes and seconds in a clock format (3-days 4:34:54). Not selecting this option displays each time division separately (3-days 4-hours 34-minutes 54-seconds).
Change Days at Midnight:
This option controls how days are counted if Hours, Minutes and Seconds are not selected as display options. Selecting this option causes the day count to change at midnight. This is probably the way you would count days if you looked at a calendar. Not selecting this option causes the day count to change at the event time.
For example, with "Change Days at Midnight" selected, an event whose time is 1:00 am would display '1-day until' until midnight of the day before the event. When "Change Days at Midnight" is not selected, the same event would display '0-days until' starting at 1:00 am of the previous day.
Limitations:
-----------
Eye On The Clock uses the Mac clock to store and compute times and dates. Because of the way that the Mac deals with time, Eye On The Clock can only support dates from 1/1/1904 through 2/6/2040. Event dates not within this range will produce incorrect calculations.
